StringToNum

StringToNum
Header:	NumberFormatting.h		Carbon status:	Supported

Converts the Pascal string representation of a base-10 number into a long integer value.

void StringToNum (
    ConstStr255Param theString, 
    SInt32 *theNum
);

Parameter descriptions

theString: A Pascal string representation of a base-10 number. The numeric string can be padded with leading zeros or with a sign.
theNum: On output, contains a pointer to the numeric value.

DISCUSSION

Unless patched by a script system with different rules, this function assumes that you are using standard numeric token processing, meaning that the Roman script system number processing rules are used.

For functions that make use of the token-processing information that is found in the tokens ('itl4') resource of script systems for converting numbers, see the sections “Using Number Format Specification Strings for International Number Formatting” and “Converting Between Strings and Floating-Point Numbers”.

The 32-bit result is negated if the string begins with a minus sign. Integer overflow occurs if the magnitude is greater than or equal to 2 raised to the 31st power. StringToNum performs the negation using the two’s complement method: the state of each bit is reversed and then 1 is added to the result. For example, here are possible results produced by StringToNum:

The value of theString is “-23”. StringToNum returns the value -23 in theNum.
The value of theString is “-0”. StringToNum returns the value 0 in theNum.
The value of theString is “055”. StringToNum returns the value 55 in theNum.
The value of theString is “2147483648” (magnitude is 2^31). StringToNum returns the value –2147483648 in theNum.
The value of theString is “–2147483648”. StringToNum returns the value –2147483648 in theNum.
The value of theString is “4294967295” (magnitude is 2^32–1). StringToNum returns the value -1 in theNum.
The value of theString is “–4294967295”. StringToNum returns the value 1 in theNum.

StringToNum does not check whether the characters in the string are between 0 and 9; instead, it takes advantage of the fact that the ASCII values for these characters are $30 through $39, and masks the last four bits for use as a digit. For example, StringToNum converts 2: to the number 30 since the character code for the colon (:) is $3A. Because StringToNum operates this way, spaces are treated as zeros (the character code for a space is $20), and other characters do get converted into numbers. For example, the character codes for 'C', 'A', and 'T' are $43, $41, and $54 respectively. Hence, the strings ëCAT’, ë+CAT’, and ë-CAT’ would produce the results 314, 314, and -314.

One consequence of this conversion method is that StringToNum does not ignore thousand separators (the “,” character in the United States), which can lead to improper conversions. It is a good idea to ensure that all characters in theString are valid digits before you call StringToNum.

SPECIAL CONSIDERATIONS

StringToNum may move memory; your application should not call this function at interrupt time.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.